---
title: "Reader App"
type: entity
created: 2026-04-18
updated: 2026-04-18
sources: ["raw/articles/06-reading-telemetry.md", "raw/notes/memory.md"]
tags: [service, reader-app, pwa, capacitor, reading]
---

# Reader App

The Reader App is the child-facing reading application — the primary product interface that children interact with daily. Everything else on the platform exists to support and enhance what happens here.

## Service Details

| Attribute | Value |
|---|---|
| Domain | app.readingtester.com |
| Server port | 3125 |
| Client port | 5193 |
| Code location | `/home/ubuntu/reader/` |
| Database | `reader_app` on shared MySQL |
| Status | ✅ Live |

## Stack

React 19 + Vite + TypeScript (client) · Express + tRPC + Drizzle + MySQL (server)

**Platform:** PWA first → Capacitor wrapper for iOS/Android App Store (one codebase, all platforms)

## Reading Surface Design

⚠️ **Non-Negotiable (Sig):** Warm cream reading surface, NOT dark. Dark mode drops reading comprehension 14% in studies.

- **Background:** Warm cream (`#F5E6C8` sepia, `#ffffff` day) — never pure black
- **Font size:** 24px minimum body text
- **Line height:** 2.2 for comfortable reading
- **No decorative elements during reading** — distracts children

## Core Features

### Finger-Follow Reading
Children drag their finger over text. Words highlight in `#FCC128` (Lightning Yellow). TTS speaks each touched word.

- **Debounce:** 120ms — prevents word spam on fast drags
- **iOS audio gate:** Handles iOS audio context unlock on first touch
- **Word counting:** Every touched word counts toward Miles
- **Pedagogical basis:** Montessori finger-follow technique — strong evidence base for early readers

### TTS (Text-to-Speech)
- **Provider:** ElevenLabs (active). Azure Neural TTS coded and ready — awaiting Sig to provide key via portal.azure.com → Speech Services
- **Karaoke mode:** Word-by-word highlight. Speed 0.5×–1.5× (0.75× default). Already-read text dims.
- **Toggle:** Per-book, per-session preference

### Miles + Tokens
- **Miles:** 100 words read = 1 mile (tracked in DB)
- **Tokens:** 10 miles = 1 token (tokens unlock books — not prizes)
- **Design rule:** No leaderboards. No token loss. Tokens unlock **books**, not external rewards
- **UI reward screen:** ⬜ Not yet built

### Speedread RSVP
- **One word at a time** at configurable WPM
- **Eligibility:** Ages 8+ AND FK level ≥ 3.0 only
- **Maximum:** 10 minutes per session. Never default. Opt-in only.
- **Word counting:** RSVP words count toward miles/practice only — NOT toward "books read" count

### Word Tap Vocabulary Popup
- Tap any word → definition popup
- Logged as `word_tapped` event → [[Telemetry Service]] → [[Learner Bot]] vocabulary gap tracking

### Reading Support Panel (Aa button)
- Font selector: Classic serif / Lexend / OpenDyslexic
- Bionic Reading mode
- Wide Spacing (WCAG: 0.12em letter + 0.16em word)
- Colour Overlay: yellow / blue / green / pink / grey
- Reading Ruler

### Themes
Persisted to localStorage:
- Day: `bg #ffffff`
- Sepia: `bg #F5E6C8`
- Night: `bg #1c1c1e`

### Offline Support
- **Service Worker** (sw.ts) + IndexedDB telemetry queue
- All events queued offline: workbox-background-sync, max 72h, exponential backoff (5s → 30s → 2min → 10min)
- Auto-replay on reconnect in order

### Adaptive Content
Every page render passes through the [[Adaptive Engine]] (`adapt.readingtester.com`):
- `POST /api/v1/level-page { book_id, page_number, source_text, target_fk_grade, learner_id }`
- Cache hit: <50ms
- Cache miss: ~1–2s GPT-4o latency (loading state shown)

## Book Catalog

- **9,089 books** available from CDN
- Native HTML page renderer (cheerio word-span injection)
- Vertical text-only portrait mode (landscape not yet built)

## Features Not Yet Built

| Feature | Status |
|---|---|
| Landscape mode (full-bleed illustration) | ⬜ Not built |
| Comprehension quiz (post-book) | ⬜ Not built |
| Placement test (first login) | ⬜ Not built |
| Miles/Tokens reward screen | ⬜ Not built |

## Key Tables Owned

| Table | Status | Purpose |
|---|---|---|
| `reading_sessions` | ✅ | Book session tracking (open/completed/abandoned) |
| `quiz_attempts` | ✅ | Comprehension quiz results |
| `placement_results` | ✅ | Initial FK placement scores |

## Related Pages

- [[concepts/user-flows/Student Flow]] — full child reading journey
- [[entities/Telemetry Service]] — event collection service
- [[entities/Adaptive Engine]] — FK leveling for every page
- [[concepts/architecture/Data Flow]] — reader → telemetry → bot data flow